iframe
elementSupport in all current engines.
Support in all current engines.
src
— Address of the resourcesrcdoc
— A document to render in the iframe
name
— Name of nested browsing contextsandbox
— Security rules for nested contentallow
— Permissions policy to be applied to the iframe
's contentsallowfullscreen
— Whether to allow the iframe
's contents to use requestFullscreen()
allowpaymentrequest
— Whether the iframe
's contents are allowed to use the PaymentRequest
interface to make payment requestswidth
— Horizontal dimensionheight
— Vertical dimensionreferrerpolicy
— Referrer policy for fetches initiated by the elementloading
— Used when determining loading deferral[Exposed =Window ]
interface HTMLIFrameElement : HTMLElement {
[HTMLConstructor ] constructor ();
[CEReactions ] attribute USVString src ;
[CEReactions ] attribute DOMString srcdoc ;
[CEReactions ] attribute DOMString name ;
[SameObject , PutForwards =value ] readonly attribute DOMTokenList sandbox ;
[CEReactions ] attribute DOMString allow ;
[CEReactions ] attribute boolean allowFullscreen ;
[CEReactions ] attribute boolean allowPaymentRequest ;
[CEReactions ] attribute DOMString width ;
[CEReactions ] attribute DOMString height ;
[CEReactions ] attribute DOMString referrerPolicy ;
[CEReactions ] attribute DOMString loading ;
readonly attribute Document ? contentDocument ;
readonly attribute WindowProxy ? contentWindow ;
Document ? getSVGDocument ();
// also has obsolete members
};
The iframe
element represents its nested browsing
context.
The src
attribute gives the URL
of a page that the element's nested browsing context is to contain. The attribute, if
present, must be a valid non-empty URL potentially surrounded by spaces. If the itemprop
attribute is specified on an iframe
element,
then the src
attribute must also be specified.
Support in all current engines.
The srcdoc
attribute gives the content of the page that the
element's nested browsing context is to contain. The value of the attribute is the
source of an iframe
srcdoc
document.
The srcdoc
attribute, if present, must have a value
using the HTML syntax that consists of the following syntactic components, in the
given order:
html
element.The above requirements apply in XML documents as well.
Here a blog uses the srcdoc
attribute in conjunction
with the sandbox
attribute described below to provide
users of user agents that support this feature with an extra layer of protection from script
injection in the blog post comments:
< article >
< h1 > I got my own magazine!</ h1 >
< p > After much effort, I've finally found a publisher, and so now I
have my own magazine! Isn't that awesome?! The first issue will come
out in September, and we have articles about getting food, and about
getting in boxes, it's going to be great!</ p >
< footer >
< p > Written by < a href = "/users/cap" > cap</ a > , 1 hour ago.
</ footer >
< article >
< footer > Thirteen minutes ago, < a href = "/users/ch" > ch</ a > wrote: </ footer >
< iframe sandbox srcdoc = "<p>did you get a cover picture yet?" ></ iframe >
</ article >
< article >
< footer > Nine minutes ago, < a href = "/users/cap" > cap</ a > wrote: </ footer >
< iframe sandbox srcdoc = "<p>Yeah, you can see it <a href="/gallery?mode=cover&amp;page=1">in my gallery</a>." ></ iframe >
</ article >
< article >
< footer > Five minutes ago, < a href = "/users/ch" > ch</ a > wrote: </ footer >
< iframe sandbox srcdoc = "<p>hey that's earl's table.
<p>you should get earl&amp;me on the next cover." ></ iframe >
</ article >
Notice the way that quotes have to be escaped (otherwise the srcdoc
attribute would end prematurely), and the way raw
ampersands (e.g. in URLs or in prose) mentioned in the sandboxed content have to be
doubly escaped — once so that the ampersand is preserved when originally parsing
the srcdoc
attribute, and once more to prevent the
ampersand from being misinterpreted when parsing the sandboxed content.
Furthermore, notice that since the DOCTYPE is optional in
iframe
srcdoc
documents, and the html
,
head
, and body
elements have optional
start and end tags, and the title
element is also optional in iframe
srcdoc
documents, the markup in a srcdoc
attribute can be
relatively succinct despite representing an entire document, since only the contents of the
body
element need appear literally in the syntax. The other elements are still
present, but only by implication.
In the HTML syntax, authors need only remember to use U+0022
QUOTATION MARK characters (") to wrap the attribute contents and then to escape all U+0026
AMPERSAND (&) and U+0022 QUOTATION MARK (") characters, and to specify the sandbox
attribute, to ensure safe embedding of content. (And
remember to escape ampersands before quotation marks, to ensure quotation marks become "
and not &quot;.)
In XML the U+003C LESS-THAN SIGN character (<) needs to be escaped as well. In order to prevent attribute-value normalization, some of XML's whitespace characters — specifically U+0009 CHARACTER TABULATION (tab), U+000A LINE FEED (LF), and U+000D CARRIAGE RETURN (CR) — also need to be escaped. [XML]
If the src
attribute and the srcdoc
attribute are both specified together, the srcdoc
attribute takes priority. This allows authors to provide
a fallback URL for legacy user agents that do not support the srcdoc
attribute.
When an iframe
element element is inserted into a document whose browsing
context is non-null, the user agent must run these steps:
Create a new nested browsing context for element.
Process the iframe
attributes for the "first time".
When an iframe
element is removed
from a document, the user agent must discard the element's nested browsing context, if it is not null,
and then set the element's nested browsing context to null.
This happens without any unload
events firing
(the element's nested browsing context and its Document
are discarded, not unloaded).
Whenever an iframe
element with a non-null nested browsing context
has its srcdoc
attribute set, changed, or removed, the
user agent must process the iframe
attributes.
Similarly, whenever an iframe
element with a non-null nested browsing
context but with no srcdoc
attribute specified has
its src
attribute set, changed, or removed, the user agent
must process the iframe
attributes.
When the user agent is to process the iframe
attributes, it must run
the first appropriate steps from the following list:
srcdoc
attribute is specifiedSet the iframe
's current navigation was lazy loaded boolean
to false.
If the will lazy load element steps given the iframe
element
return true, then:
Set the iframe
's lazy load resumption steps to the rest of
this algorithm starting with the step labeled
navigate to the srcdoc resource.
Set the iframe
's current navigation was lazy loaded boolean
to true.
Start intersection-observing a lazy loading element for the
iframe
element.
Return.
Navigate to the srcdoc resource: Navigate the
element's nested browsing context to a new response whose url
list consists of about:srcdoc
, header list consists of `Content-Type
`/`text/html
`, body is the value of the attribute, CSP list is a clone
of the iframe
element's node document's CSP list, HTTPS state is the HTTPS state of the iframe
element's
node document.
The resulting Document
must be considered an iframe
srcdoc
document.
src
attribute
specified, and the user agent is processing the iframe
's attributes for the "first
time"Queue an element task on the DOM manipulation task source given
the iframe
element and the iframe load event steps.
The otherwise steps for iframe
or frame
elements are as
follows:
If the element has no src
attribute specified, or its
value is the empty string, let url be the URL
"about:blank
".
Otherwise, parse the value of the src
attribute, relative to the element's node
document.
If that is not successful, then let url be the URL
"about:blank
". Otherwise, let url be the resulting URL
record.
If there exists an ancestor browsing context whose active document's URL, ignoring fragments, is equal to url, then return.
Let resource be a new request whose url is url and whose referrer policy is the current state of the
element's referrerpolicy
content
attribute.
Set the iframe
's current navigation was lazy loaded boolean to
false.
If the element is an iframe
element, and the will lazy load element
steps given the element return true, then:
Set the iframe
's lazy load resumption steps to the rest of
this algorithm starting with the step labeled navigate to the resource.
Set the iframe
's current navigation was lazy loaded boolean
to true.
Start intersection-observing a lazy loading element for the
iframe
element.
Return.
Navigate to the resource: Navigate the element's nested browsing context to resource.
Any navigation required of the user agent in the process
the iframe
attributes algorithm must use the iframe
element's
node document's browsing context as the
source browsing context.
Furthermore, if the active document of the element's nested browsing context before such a navigation was not completely loaded at the time of the new navigation, then the navigation must be completed with replacement enabled.
Similarly, if the element's nested browsing context's session history
contained only one Document
when the process the iframe
attributes algorithm was invoked, and that was the about:blank
Document
created when the element's nested browsing context was created,
then any navigation required of the user agent in that algorithm
must be completed with replacement enabled.
When a Document
in an iframe
is marked as completely
loaded, the user agent must run the iframe load event steps.
A load
event is also fired at the
iframe
element when it is created if no other data is loaded in it.
Each Document
has an iframe load in progress flag and a mute
iframe load flag. When a Document
is created, these flags must be unset for
that Document
.
The iframe load event steps are as follows:
Let child document be the active document of the
iframe
element's nested browsing context (which cannot be null at this
point).
If child document has its mute iframe load flag set, return.
Set child document's iframe load in progress flag.
Fire an event named load
at the iframe
element.
Unset child document's iframe load in progress flag.
This, in conjunction with scripting, can be used to probe the URL space of the local network's HTTP servers. User agents may implement cross-origin access control policies that are stricter than those described above to mitigate this attack, but unfortunately such policies are typically not compatible with existing web content.
If an element type potentially delays the load event, then for each element element of that type, the user agent must delay the load event of element's node document if element's nested browsing context is non-null and any of the following are true:
element's nested browsing context's active document is not ready for post-load tasks.
Anything is delaying the load event of element's nested browsing context's active document.
element's nested browsing context is in the delaying load
events mode.
If, during the handling of the load
event,
element's nested browsing context is again navigated, that will further delay the load event.
Each iframe
element has an associated current navigation was lazy
loaded boolean, initially false. It is set and unset in the process the
iframe
attributes algorithm.
An iframe
element whose current navigation was lazy loaded boolean is
false potentially delays the load event.
If, when the element is created, the srcdoc
attribute is not set, and the src
attribute is either also not set or set but its value cannot be
parsed, the browsing context will remain at the initial
about:blank
page.
If the user navigates away from this page, the
iframe
's nested browsing context's WindowProxy
object will
proxy new Window
objects for new Document
objects, but the src
attribute will not change.
The name
attribute, if present, must be a
valid browsing context name. The given value is used to name the element's
nested browsing context if present when that is created.
Support in all current engines.
The sandbox
attribute, when specified,
enables a set of extra restrictions on any content hosted by the iframe
. Its value
must be an unordered set of unique space-separated tokens that are ASCII
case-insensitive. The allowed values are allow-forms
, allow-modals
, allow-orientation-lock
, allow-pointer-lock
, allow-popups
, allow-popups-to-escape-sandbox
,
allow-presentation
, allow-same-origin
, allow-scripts
, allow-top-navigation
, allow-top-navigation-by-user-activation
,
and allow-downloads
.
When the attribute is set, the content is treated as being from a unique origin,
forms, scripts, and various potentially annoying APIs are disabled, links are prevented from
targeting other browsing contexts, and plugins are secured.
The allow-same-origin
keyword causes
the content to be treated as being from its real origin instead of forcing it into a unique
origin; the allow-top-navigation
keyword allows the content to navigate its top-level browsing context;
the allow-top-navigation-by-user-activation
keyword behaves similarly but allows such navigation only when the
browsing context's active window has transient activation; and the allow-forms
, allow-modals
, allow-orientation-lock
, allow-pointer-lock
, allow-popups
, allow-presentation
, allow-scripts
, and allow-popups-to-escape-sandbox
keywords re-enable forms, modal dialogs, screen orientation lock, the pointer lock API, popups,
the presentation API, scripts, and the creation of unsandboxed auxiliary browsing contexts respectively. [POINTERLOCK]
[SCREENORIENTATION] [PRESENTATION]
The allow-top-navigation
and allow-top-navigation-by-user-activation
keywords must not both be specified, as doing so is redundant; only allow-top-navigation
will have an effect
in such non-conformant markup.
Setting both the allow-scripts
and allow-same-origin
keywords together when the
embedded page has the same origin as the page containing the iframe
allows the embedded page to simply remove the sandbox
attribute and then reload itself, effectively breaking out of the sandbox altogether.
These flags only take effect when the nested browsing context of
the iframe
element is navigated. Removing them, or
removing the entire sandbox
attribute, has no effect on
an already-loaded page.
Potentially hostile files should not be served from the same server as the file
containing the iframe
element. Sandboxing hostile content is of minimal help if an
attacker can convince the user to just visit the hostile content directly, rather than in the
iframe
. To limit the damage that can be caused by hostile HTML content, it should be
served from a separate dedicated domain. Using a different domain ensures that scripts in the
files are unable to attack the site, even if the user is tricked into visiting those pages
directly, without the protection of the sandbox
attribute.
When an iframe
element with a sandbox
attribute has its nested browsing context created (before the initial
about:blank
Document
is created), and when an iframe
element's sandbox
attribute is set or changed while it
has a nested browsing context, the user agent must parse the sandboxing directive using the attribute's value as the
input and the iframe
element's iframe
sandboxing flag
set as the output.
When an iframe
element's sandbox
attribute is removed while it has a non-null nested browsing context, the user agent
must empty the iframe
element's iframe
sandboxing flag
set.
In this example, some completely-unknown, potentially hostile, user-provided HTML content is embedded in a page. Because it is served from a separate domain, it is affected by all the normal cross-site restrictions. In addition, the embedded page has scripting disabled, plugins disabled, forms disabled, and it cannot navigate any frames or windows other than itself (or any frames or windows it itself embeds).
< p > We're not scared of you! Here is your content, unedited:</ p >
< iframe sandbox src = "https://usercontent.example.net/getusercontent.cgi?id=12193" ></ iframe >
It is important to use a separate domain so that if the attacker convinces the user to visit that page directly, the page doesn't run in the context of the site's origin, which would make the user vulnerable to any attack found in the page.
In this example, a gadget from another site is embedded. The gadget has scripting and forms enabled, and the origin sandbox restrictions are lifted, allowing the gadget to communicate with its originating server. The sandbox is still useful, however, as it disables plugins and popups, thus reducing the risk of the user being exposed to malware and other annoyances.
< iframe sandbox = "allow-same-origin allow-forms allow-scripts"
src = "https://maps.example.com/embedded.html" ></ iframe >
Suppose a file A contained the following fragment:
< iframe sandbox = "allow-same-origin allow-forms" src = B ></ iframe >
Suppose that file B contained an iframe also:
< iframe sandbox = "allow-scripts" src = C ></ iframe >
Further, suppose that file C contained a link:
< a href = D > Link</ a >
For this example, suppose all the files were served as text/html
.
Page C in this scenario has all the sandboxing flags set. Scripts are disabled, because the
iframe
in A has scripts disabled, and this overrides the allow-scripts
keyword set on the
iframe
in B. Forms are also disabled, because the inner iframe
(in B)
does not have the allow-forms
keyword
set.
Suppose now that a script in A removes all the sandbox
attributes in A and B.
This would change nothing immediately. If the user clicked the link in C, loading page D into the
iframe
in B, page D would now act as if the iframe
in B had the allow-same-origin
and allow-forms
keywords set, because that was the
state of the nested browsing context in the iframe
in A when page B was
loaded.
Generally speaking, dynamically removing or changing the sandbox
attribute is ill-advised, because it can make it quite
hard to reason about what will be allowed and what will not.
The allow
attribute, when specified,
determines the container policy that will be used
when the permissions policy for a
Document in the iframe
's nested browsing context is
initialized. Its value must be a serialized
permissions policy. [PERMISSIONSPOLICY]
In this example, an iframe
is used to embed a map from an online navigation
service. The allow
attribute is used to enable the
Geolocation API within the nested context.
< iframe src = "https://maps.example.com/" allow = "geolocation" ></ iframe >
The allowfullscreen
attribute is a
boolean attribute. When specified, it indicates that Document
objects in
the iframe
element's nested browsing context will be initialized with a
permissions policy which allows the "fullscreen
" feature to be used from any origin. This is enforced by
the process permissions policy
attributes algorithm. [PERMISSIONSPOLICY]
Here, an iframe
is used to embed a player from a video site. The allowfullscreen
attribute is needed to enable the
player to show its video fullscreen.
< article >
< header >
< p >< img src = "/usericons/1627591962735" > < b > Fred Flintstone</ b ></ p >
< p >< a href = "/posts/3095182851" rel = bookmark > 12:44</ a > — < a href = "#acl-3095182851" > Private Post</ a ></ p >
</ header >
< p > Check out my new ride!</ p >
< iframe src = "https://video.example.com/embed?id=92469812" allowfullscreen ></ iframe >
</ article >
The allowpaymentrequest
attribute is a boolean attribute. When specified, it indicates that
Document
objects in the iframe
element's nested browsing
context will be initialized with a permissions policy which allows the "payment
" feature to be used to make payment requests from any
origin. This is enforced by the Process permissions policy attributes
algorithm. [PERMISSIONSPOLICY]
None of these attributes, allow
,
allowfullscreen
or allowpaymentrequest
, can grant access to a feature
in an iframe
element's nested browsing context if the element's
node document is not already allowed to use that feature.
To determine whether a Document
object document
is allowed to use the policy-controlled-feature feature,
run these steps:
If document's browsing context is null, then return false.
If document's browsing context's active document is not document, then return false.
If the result of running is feature enabled in document
for origin on feature, document, and document's
origin is "Enabled
", then return true.
Return false.
Because they only influence the permissions policy of the nested browsing
context's active document, the allow
,
allowfullscreen
and allowpaymentrequest
attributes only take effect
when the nested browsing context of the iframe
is navigated. Adding or removing them has no effect on an already-loaded
document.
The iframe
element supports dimension attributes for cases where the
embedded content has specific dimensions (e.g. ad units have well-defined dimensions).
An iframe
element never has fallback content, as it will always
create a new nested browsing context, regardless of whether the specified initial
contents are successfully used.
The referrerpolicy
attribute is a
referrer policy attribute. Its purpose is to set the referrer policy
used when processing the iframe
attributes. [REFERRERPOLICY]
The loading
attribute is a lazy
loading attribute. Its purpose is to indicate the policy for loading iframe
elements that are outside the viewport.
When the loading
attribute's state is changed to the
Eager state, the user agent must run these
steps:
Let resumptionSteps be the iframe
element's lazy load
resumption steps.
If resumptionSteps is null, then return.
Set the iframe
's lazy load resumption steps to null.
Invoke resumptionSteps.
Descendants of iframe
elements represent nothing. (In legacy user agents that do
not support iframe
elements, the contents would be parsed as markup that could act as
fallback content.)
The HTML parser treats markup inside iframe
elements as
text.
Support in all current engines.
The IDL attributes src
, srcdoc
, name
, sandbox
, and allow
must reflect the respective content
attributes of the same name.
The supported tokens for sandbox
's DOMTokenList
are the allowed
values defined in the sandbox
attribute and supported by
the user agent.
The allowFullscreen
IDL attribute
must reflect the allowfullscreen
content attribute.
HTMLIFrameElement/allowPaymentRequest
The allowPaymentRequest
IDL
attribute must reflect the allowpaymentrequest
content attribute.
HTMLIFrameElement/referrerPolicy
Support in all current engines.
The referrerPolicy
IDL attribute
must reflect the referrerpolicy
content attribute, limited to only known values.
The loading
IDL attribute must
reflect the loading
content attribute,
limited to only known values.
HTMLIFrameElement/contentDocument
Support in all current engines.
The contentDocument
IDL attribute,
on getting, must return the iframe
element's content document.
HTMLIFrameElement/contentWindow
Support in all current engines.
The contentWindow
IDL attribute must
return the WindowProxy
object of the iframe
element's nested
browsing context, if its nested browsing context is non-null, or null
otherwise.
Here is an example of a page using an iframe
to include advertising from an
advertising broker:
< iframe src = "https://ads.example.com/?customerid=923513721&format=banner"
width = "468" height = "60" ></ iframe >
embed
elementSupport in all current engines.
Support in all current engines.
src
— Address of the resourcetype
— Type of embedded resourcewidth
— Horizontal dimensionheight
— Vertical dimension[Exposed =Window ]
interface HTMLEmbedElement : HTMLElement {
[HTMLConstructor ] constructor ();
[CEReactions ] attribute USVString src ;
[CEReactions ] attribute DOMString type ;
[CEReactions ] attribute DOMString width ;
[CEReactions ] attribute DOMString height ;
Document ? getSVGDocument ();
// also has obsolete members
};
Depending on the type of content instantiated by the
embed
element, the node may also support other
interfaces.
The embed
element provides an integration point for an external (typically
non-HTML) application or interactive content.
The src
attribute gives the URL of
the resource being embedded. The attribute, if present, must contain a valid non-empty URL
potentially surrounded by spaces.
Authors should avoid referencing untrusted resources, as such a resource can be used to instantiate plugins or run scripts, even if the author has used features such as the Flash "allowScriptAccess" parameter.
If the itemprop
attribute is specified on an
embed
element, then the src
attribute must also
be specified.
The type
attribute, if present, gives the
MIME type by which the plugin to instantiate is selected. The value must be a
valid MIME type string. If both the type
attribute and the src
attribute are present, then the type
attribute must specify the same type as the explicit Content-Type metadata of the resource given by the src
attribute.
While any of the following conditions are occurring, any plugin instantiated for
the element must be removed, and the embed
element represents
nothing:
The element has neither a src
attribute nor a type
attribute.
The element has a media element ancestor.
The element has an ancestor object
element that is not showing its
fallback content.
An embed
element is said to be potentially
active when the following conditions are all met simultaneously:
src
attribute set or a type
attribute set (or both).src
attribute is either absent or its value
is not the empty string.object
element that is not showing its
fallback content.Whenever an embed
element that was not potentially active becomes potentially active, and whenever a potentially active embed
element that is
remaining potentially active and has its src
attribute set, changed, or removed or its type
attribute set, changed, or removed, the user agent must
queue an element task on the embed task source given the element
to run the embed
element setup steps for that element.
The embed
element setup steps for a given embed
element
element are as follows:
If another task has since been queued to run the
embed
element setup steps for element, then return.
If the Should element be blocked a priori by Content Security
Policy? algorithm returns "Blocked
" when executed on
element, then return. [CSP]
If element has a src
attribute set, then:
Let url be the result of parsing the value
of element's src
attribute, relative to
element's node document.
If url is failure, then return.
Let request be a new request whose
url is url, client is element's node
document's relevant settings object, destination is "embed
",
credentials mode is "include
", mode is "navigate
", and whose use-URL-credentials flag is set.
Fetch request.
Fetching the resource must delay the load event of element's node document.
To process response for the response response:
If another task has since been queued to run
the embed
element setup steps for element, then
return.
If response is a network error, then fire an event named load
at element, and return.
Let type be the result of determining the type of content given element and response.
Switch on type:
Display no plugin for element.
image/svg+xml
If element's nested browsing context is null, then create a new nested browsing context for element.
Navigate element's nested browsing context to response, with replacement enabled, and with element's node document's browsing context as the source browsing context.
element's src
attribute
does not get updated if the browsing context gets further navigated to other
locations.
element now represents its nested browsing context.
When the Document
of element's nested browsing
context is marked as completely loaded, queue an element
task on the DOM manipulation task source given element to
fire an event named load
at element.
Display a plugin for element, given type and response.
Otherwise:
Let type be the value of element's type
attribute.
If type is a type that a plugin supports, then display a plugin for element given type.
Otherwise, display no plugin for element.
To determine the type of the content given an
embed
element element and a response response, run the following steps:
If element has a type
attribute, and that
attribute's value is a type that a plugin supports, then return the value of the
type
attribute.
If the path component of response's url matches a pattern that a plugin supports, then return the type that that plugin can handle.
For example, a plugin might say that it can handle URLs with path components that end with the four character string
".swf
".
If response has explicit Content-Type metadata, and that value is a type that a plugin supports, then return that value.
Return null.
It is intentional that the above algorithm allows response to have a non-ok status. This allows servers to return data for plugins even with error responses (e.g., HTTP 500 Internal Server Error codes can still contain plugin data).
To display a plugin for an embed
element element, given a
string type and optionally a response
response:
If element's nested browsing context is not null, then:
Discard element's nested browsing context.
Set element's nested browsing context to null.
Find and instantiate an appropriate plugin based on type, replacing any previously-instantiated plugin for element. If response was given, forward it to the plugin.
element now represents this plugin instance.
Once the plugin, and response if given, are completely loaded, queue an
element task on the DOM manipulation task source give element to
fire an event named load
at element.
To display no plugin for an embed
element element:
If element's nested browsing context is not null, then:
Discard element's nested browsing context.
Set element's nested browsing context to null.
Display an indication that no plugin could be found for element, replacing any previously-instantiated plugin for element.
element now represents nothing.
The embed
element has no fallback content; its
descendants are ignored.
Whenever an embed
element that was potentially
active stops being potentially active, any
plugin that had been instantiated for that element must be unloaded.
When a plugin is to be instantiated but it cannot be secured and the sandboxed plugins browsing context
flag is set on the embed
element's node document's active
sandboxing flag set, then the user agent must not instantiate the plugin, and
must instead render the embed
element in a manner that conveys that the
plugin was disabled. The user agent may offer the user the option to override the
sandbox and instantiate the plugin anyway; if the user invokes such an option, the
user agent must act as if the conditions above did not apply for the purposes of this element.
Plugins that cannot be secured are disabled in sandboxed browsing contexts because they might not honor the restrictions imposed by the sandbox (e.g. they might allow scripting even when scripting in the sandbox is disabled). User agents should convey the danger of overriding the sandbox to the user if an option to do so is provided.
The embed
element potentially delays the load event.
Any namespace-less attribute other than name
, align
, hspace
, and vspace
may be
specified on the embed
element, so long as its name is XML-compatible
and contains no ASCII upper alphas. These attributes are
then passed as parameters to the plugin.
All attributes in HTML documents get lowercased automatically, so the restriction on uppercase letters doesn't affect such documents.
The four exceptions are to exclude legacy attributes that have side-effects beyond just sending parameters to the plugin.
The user agent should pass the names and values of all the attributes of the embed
element that have no namespace to the plugin used, when one is instantiated.
The HTMLEmbedElement
object representing the element must expose the scriptable
interface of the plugin instantiated for the embed
element, if any.
The embed
element supports dimension attributes.
The IDL attributes src
and type
each must reflect the respective
content attributes of the same name.
Here's a way to embed a resource that requires a proprietary plugin, like Flash:
< embed src = "catgame.swf" >
If the user does not have the plugin (for example if the plugin vendor doesn't support the user's platform), then the user will be unable to use the resource.
To pass the plugin a parameter "quality" with the value "high", an attribute can be specified:
< embed src = "catgame.swf" quality = "high" >
This would be equivalent to the following, when using an object
element
instead:
< object data = "catgame.swf" >
< param name = "quality" value = "high" >
</ object >
object
elementSupport in all current engines.
Support in all current engines.
usemap
attribute: Interactive content.param
elements, then, transparent.data
— Address of the resourcetype
— Type of embedded resourcename
— Name of nested browsing contextusemap
— Name of image map to useform
— Associates the element with a form
elementwidth
— Horizontal dimensionheight
— Vertical dimension[Exposed =Window ]
interface HTMLObjectElement : HTMLElement {
[HTMLConstructor ] constructor ();
[CEReactions ] attribute USVString data ;
[CEReactions ] attribute DOMString type ;
[CEReactions ] attribute DOMString name ;
[CEReactions ] attribute DOMString useMap ;
readonly attribute HTMLFormElement ? form ;
[CEReactions ] attribute DOMString width ;
[CEReactions ] attribute DOMString height ;
readonly attribute Document ? contentDocument ;
readonly attribute WindowProxy ? contentWindow ;
Document ? getSVGDocument ();
readonly attribute boolean willValidate ;
readonly attribute ValidityState validity ;
readonly attribute DOMString validationMessage ;
boolean checkValidity ();
boolean reportValidity ();
void setCustomValidity (DOMString error );
// also has obsolete members
};
Depending on the type of content instantiated by the
object
element, the node also supports other
interfaces.
The object
element can represent an external resource, which, depending on the
type of the resource, will either be treated as an image, as a child browsing
context, or as an external resource to be processed by a plugin.
The data
attribute, if present, specifies the
URL of the resource. If present, the attribute must be a valid non-empty URL
potentially surrounded by spaces.
Authors should avoid referencing untrusted resources, as such a resource can be used to instantiate plugins or run scripts, even if the author has used features such as the Flash "allowScriptAccess" parameter.
The type
attribute, if present, specifies the
type of the resource. If present, the attribute must be a valid MIME type string.
At least one of either the data
attribute or the type
attribute must be present.
If the itemprop
attribute is specified on an object
element, then the data
attribute must also be specified.
The name
attribute, if present, must be a
valid browsing context name. The given value is used to name the element's
nested browsing context, if applicable, and if present when the element's
nested browsing context is created.
Whenever one of the following conditions occur:
object
elements changes to or from showing its
fallback content,
classid
attribute is set, changed, or
removed,
classid
attribute is not present, and
its data
attribute is set, changed, or removed,
classid
attribute nor its
data
attribute are present, and its type
attribute is set, changed, or removed,
...the user agent must queue an element task on the DOM manipulation task
source given the object
element to run the following steps to (re)determine
what the object
element represents. This task
being queued or actively running must delay the load
event of the element's node document.
If the user has indicated a preference that this object
element's fallback
content be shown instead of the element's usual behavior, then jump to the step below
labeled fallback.
For example, a user could ask for the element's fallback content to be shown because that content uses a format that the user finds more accessible.
If the element has an ancestor media element, or has an ancestor
object
element that is not showing its fallback content, or
if the element is not in a document whose browsing context is non-null, or if the element's node
document is not fully active, or if the element is still in the stack
of open elements of an HTML parser or XML parser, or if the
element is not being rendered, or if the Should element be blocked
a priori by Content Security Policy? algorithm returns "Blocked
" when executed on the element, then jump to the step below labeled
fallback. [CSP]
If the classid
attribute is present, and has a
value that isn't the empty string, then: if the user agent can find a plugin
suitable according to the value of the classid
attribute, and either plugins aren't being sandboxed or that
plugin can be secured, then that
plugin should be used, and the value of the data
attribute, if any, should be passed to the
plugin. If no suitable plugin can be found, or if the
plugin reports an error, jump to the step below labeled fallback.
If the data
attribute is present and its value is
not the empty string, then:
If the type
attribute is present and its value is
not a type that the user agent supports, and is not a type that the user agent can find a
plugin for, then the user agent may jump to the step below labeled fallback
without fetching the content to examine its real type.
Parse the URL specified by the data
attribute, relative to the element's node
document.
If that failed, fire an event named error
at the element, then jump to the step below labeled
fallback.
Let request be a new request whose
url is the resulting URL record,
client is the element's node
document's relevant settings object, destination is "object
",
credentials mode is "include
", mode is "navigate
", and whose use-URL-credentials flag is set.
Fetch request.
Fetching the resource must delay the load event of the element's node document until the task that is queued by the networking task source once the resource has been fetched (defined next) has been run.
For the purposes of the application cache networking model, this fetch operation is not for a child browsing context (though it might end up being used for one after all, as defined below).
If the resource is not yet available (e.g. because the resource was not available in the cache, so that loading the resource required making a request over the network), then jump to the step below labeled fallback. The task that is queued by the networking task source once the resource is available must restart this algorithm from this step. Resources can load incrementally; user agents may opt to consider a resource "available" whenever enough data has been obtained to begin processing the resource.
If the load failed (e.g. there was an HTTP 404 error, there was a DNS error), fire an event named error
at the element, then jump to the step below labeled fallback.
Determine the resource type, as follows:
Let the resource type be unknown.
If the user agent is configured to strictly obey Content-Type headers for this resource, and the resource has associated Content-Type metadata, then let the resource type be the type specified in the resource's Content-Type metadata, and jump to the step below labeled handler.
This can introduce a vulnerability, wherein a site is trying to embed a resource that uses a particular plugin, but the remote site overrides that and instead furnishes the user agent with a resource that triggers a different plugin with different security characteristics.
If there is a type
attribute present on the
object
element, and that attribute's value is not a type that the user agent
supports, but it is a type that a plugin supports, then let the resource type be the type specified in that type
attribute, and jump to the step below labeled
handler.
Run the appropriate set of steps from the following list:
Let binary be false.
If the type specified in the resource's Content-Type
metadata is "text/plain
", and the result of applying the rules for distinguishing if a resource is
text or binary to the resource is that the resource is not
text/plain
, then set binary to true.
If the type specified in the resource's Content-Type
metadata is "application/octet-stream
", then set binary to true.
If binary is false, then let the resource type be the type specified in the resource's Content-Type metadata, and jump to the step below labeled handler.
If there is a type
attribute present on the
object
element, and its value is not application/octet-stream
,
then run the following steps:
If the attribute's value is a type that a plugin supports, or the
attribute's value is a type that starts with "image/
" that is
not also an XML MIME type, then let the resource type be the
type specified in that type
attribute.
Jump to the step below labeled handler.
If there is a type
attribute present on the
object
element, then let the tentative type be the type
specified in that type
attribute.
Otherwise, let tentative type be the computed type of the resource.
If tentative type is not
application/octet-stream
, then let resource type be
tentative type and jump to the step below labeled
handler.
If applying the URL parser algorithm to the URL of the specified resource (after any redirects) results in a URL record whose path component matches a pattern that a plugin supports, then let resource type be the type that that plugin can handle.
For example, a plugin might say that it can handle resources with path components that end with the four character string
".swf
".
It is possible for this step to finish, or for one of the substeps above to jump straight to the next step, with resource type still being unknown. In both cases, the next step will trigger fallback.
Handler: Handle the content as given by the first of the following cases that matches:
If the object
element's nested browsing context is non-null,
then it must be discarded and then set
to null.
If plugins are being sandboxed and the plugin that supports resource type cannot be secured, jump to the step below labeled fallback.
Otherwise, the user agent should use the plugin that supports resource type and pass the content of the resource to that plugin. If the plugin reports an error, then jump to the step below labeled fallback.
image/
"If the object
element's nested browsing context is null, then
create a new nested browsing context for the element.
If the URL of the given resource is not about:blank
, the
element's nested browsing context must then be navigated to that resource, with
replacement enabled, and with the object
element's node
document's browsing context as the
source browsing context. (The data
attribute of the object
element doesn't get updated if the browsing context
gets further navigated to other locations.)
If the URL of the given resource is about:blank
, then,
instead, the user agent must queue an element task on the DOM
manipulation task source given the object
element to fire an event named load
at the object
element. No load
event is fired at the about:blank
document
itself.
The object
element represents its nested browsing
context.
In certain situations, e.g., if the resource was fetched from an
application cache but it is an HTML file with a manifest
attribute that points to a different application cache manifest, the navigation of the browsing context will be restarted
so as to load the resource afresh from the network or a different application
cache. Even if the resource is then found to have a different type, it is still used
as part of a browsing context: only the navigate algorithm is
restarted, not this object
algorithm.
image/
", and support
for images has not been disabledIf the object
element's nested browsing context is non-null,
then it must be discarded and then set
to null.
Apply the image sniffing rules to determine the type of the image.
The object
element represents the specified image.
If the image cannot be rendered, e.g. because it is malformed or in an unsupported format, jump to the step below labeled fallback.
The given resource type is not supported. Jump to the step below labeled fallback.
If the previous step ended with the resource type being unknown, this is the case that is triggered.
The element's contents are not part of what the object
element
represents.
Return. Once the resource is completely loaded, queue an element task on the
DOM manipulation task source given the object
element to fire an event named load
at the element.
If the data
attribute is absent but the type
attribute is present, and the user agent can find a
plugin suitable according to the value of the type
attribute, and either plugins aren't being sandboxed or the plugin can be
secured, then that plugin should be used. If these conditions cannot be met, or if the
plugin reports an error, jump to the step below labeled fallback. Otherwise
return; once the plugin is completely loaded, queue an element task on the
DOM manipulation task source given the object
element to fire an event named load
at
the element.
Fallback: The object
element represents the element's
children, ignoring any leading param
element children. This is the element's
fallback content. If the element has an instantiated plugin, then
unload it. If the element's nested browsing context is non-null, then it must be
discarded and then set to null.
When the algorithm above instantiates a plugin, the user agent
should pass to the plugin used the names and values of all the attributes on the
element, in the order they were added to the element, with the attributes added by the parser
being ordered in source order, followed by a parameter named "PARAM" whose value is null, followed
by all the names and values of parameters given by
param
elements that are children of the object
element, in tree
order. If the plugin supports a scriptable interface, the
HTMLObjectElement
object representing the element should expose that interface. The
object
element represents the plugin. The
plugin is not a nested browsing context.
Plugins are considered sandboxed for the purpose of an
object
element if the sandboxed plugins browsing context flag is set on
the object
element's node document's active sandboxing flag
set.
Due to the algorithm above, the contents of object
elements act as fallback
content, used only when referenced resources can't be shown (e.g. because it returned a 404
error). This allows multiple object
elements to be nested inside each other,
targeting multiple user agents with different capabilities, with the user agent picking the first
one it supports.
The object
element potentially delays the load event.
The usemap
attribute, if present while the
object
element represents an image, can indicate that the object has an associated
image map. The attribute must be ignored if the
object
element doesn't represent an image.
The form
attribute is used to explicitly associate the
object
element with its form owner.
Constraint validation: object
elements are always barred
from constraint validation.
The object
element supports dimension attributes.
Support in all current engines.
Support in all current engines.
Support in all current engines.
Support in all current engines.
The IDL attributes data
, type
and name
each must reflect the respective
content attributes of the same name. The useMap
IDL attribute must reflect the usemap
content attribute.
The contentDocument
IDL attribute,
on getting, must return the object
element's content document.
HTMLObjectElement/contentDocument
Support in all current engines.
HTMLObjectElement/contentWindow
The contentWindow
IDL attribute must
return the WindowProxy
object of the object
element's nested
browsing context, if its nested browsing context is non-null; otherwise, it
must return null.
The willValidate
, validity
, and validationMessage
attributes, and the checkValidity()
, reportValidity()
, and setCustomValidity()
methods, are part of the
constraint validation API. The form
IDL attribute
is part of the element's forms API.
In this example, an HTML page is embedded in another using the object
element.
< figure >
< object data = "clock.html" ></ object >
< figcaption > My HTML Clock</ figcaption >
</ figure >
The following example shows how a plugin can be used in HTML (in this case the Flash plugin,
to show a video file). Fallback is provided for users who do not have Flash enabled, in this case
using the video
element to show the video for those using user agents that support
video
, and finally providing a link to the video for those who have neither Flash
nor a video
-capable browser.
< p > Look at my video:
< object type = "application/x-shockwave-flash" >
< param name = movie value = "https://video.example.com/library/watch.swf" >
< param name = allowfullscreen value = true >
< param name = flashvars value = "https://video.example.com/vids/315981" >
< video controls src = "https://video.example.com/vids/315981" >
< a href = "https://video.example.com/vids/315981" > View video</ a > .
</ video >
</ object >
</ p >
param
elementSupport in all current engines.
Support in all current engines.
object
element, before any flow content.name
— Name of parametervalue
— Value of parameter[Exposed =Window ]
interface HTMLParamElement : HTMLElement {
[HTMLConstructor ] constructor ();
[CEReactions ] attribute DOMString name ;
[CEReactions ] attribute DOMString value ;
// also has obsolete members
};
The param
element defines parameters for plugins invoked by object
elements. It does not represent anything on its own.
The name
attribute gives the name of the
parameter.
The value
attribute gives the value of the
parameter.
Both attributes must be present. They may have any value.
If both attributes are present, and if the parent element of the param
is an
object
element, then the element defines a parameter with the given name-value pair.
If either the name or value of a parameter defined
by a param
element that is the child of an object
element that
represents an instantiated plugin changes, and if that
plugin is communicating with the user agent using an API that features the ability to
update the plugin when the name or value of a parameter so changes, then the user agent must
appropriately exercise that ability to notify the plugin of the change.
The IDL attributes name
and value
must both reflect the respective
content attributes of the same name.
The following example shows how the param
element can be used to pass a parameter
to a plugin, in this case the O3D plugin.
<!DOCTYPE HTML>
< html lang = "en" >
< head >
< title > O3D Utah Teapot</ title >
</ head >
< body >
< p >
< object type = "application/vnd.o3d.auto" >
< param name = "o3d_features" value = "FloatingPointTextures" >
< img src = "o3d-teapot.png"
title = "3D Utah Teapot illustration rendered using O3D."
alt = "When O3D renders the Utah Teapot, it appears as a squat
teapot with a shiny metallic finish on which the
surroundings are reflected, with a faint shadow caused by
the lighting." >
< p > To see the teapot actually rendered by O3D on your
computer, please download and install the < a
href = "http://code.google.com/apis/o3d/docs/gettingstarted.html#install" > O3D plugin</ a > .</ p >
</ object >
< script src = "o3d-teapot.js" ></ script >
</ p >
</ body >
</ html >